Autogenerated HTML docs for v1.8.0-197-g5a907
diff --git a/RelNotes/1.8.1.txt b/RelNotes/1.8.1.txt new file mode 100644 index 0000000..107e5f3 --- /dev/null +++ b/RelNotes/1.8.1.txt
@@ -0,0 +1,151 @@ +Git v1.8.1 Release Notes +======================== + +Backward compatibility notes +---------------------------- + +In the next major release (not *this* one), we will change the +behavior of the "git push" command. + +When "git push [$there]" does not say what to push, we have used the +traditional "matching" semantics so far (all your branches were sent +to the remote as long as there already are branches of the same name +over there). We will use the "simple" semantics that pushes the +current branch to the branch with the same name, only when the current +branch is set to integrate with that remote branch. There is a user +preference configuration variable "push.default" to change this, and +"git push" will warn about the upcoming change until you set this +variable in this release. + +"git branch --set-upstream" is deprecated and may be removed in a +relatively distant future. "git branch [-u|--set-upstream-to]" has +been introduced with a saner order of arguments. + + +Updates since v1.8.0 +-------------------- + +UI, Workflows & Features + + * We used to have a workaround for a bug in ancient "less" that + causes it to exit without any output when the terminal is resized. + The bug has been fixed in "less" version 406 (June 2007), and the + workaround has been removed in this release. + + * A new configuration variable "diff.context" can be used to + give the default number of context lines in the patch output, to + override the hardcoded default of 3 lines. + + * "git format-patch" leraned the "--notes=<ref>" option to give + notes for the commit after the three-dash lines in its output. + + * "git log --grep=<pcre>" learned to honor the "grep.patterntype" + configuration set to "perl". + + * "git rm $submodule" used to punt on removing a submodule working + tree to avoid losing the repository embedded in it. Because + recent git uses a mechanism to separate the submodule repository + from the submodule working tree, "git rm" learned to detect this + case and removes the submodule working tree when it is safe. + + * "git submodule add" learned to add a new submodule at the same + path as the path where an unrelated submodule was bound to in an + existing revision via the "--name" option. + + * "git submodule sync" learned the "--recursive" option. + + * "git symbolic-ref" learned the "-d $symref" option to delete the + named symbolic ref, which is more intuitive way to spell it than + "update-ref -d --no-deref". + + +Foreign Interface + + * "git cvsimport" can be told to record timezones (other than GMT) + per-author via its author info file. + + * The remote helper interface to interact with subversion + repositories (one of the GSoC 2012 projects) has been merged. + + +Performance, Internal Implementation, etc. + + * The logic to generate the initial advertisement from + "upload-pack" (what is invoked by "git fetch" on the other side + of the connection) to list what refs are available in the + repository has been optimized. + + * The logic to find set of attributes that match a given path has + been optimized. + + +Also contains minor documentation updates and code clean-ups. + + +Fixes since v1.8.0 +------------------ + +Unless otherwise noted, all the fixes since v1.8.0 in the maintenance +track are contained in this release (see release notes to them for +details). + + * The configuration parser had an unnecessary hardcoded limit on + variable names that was not checked consistently. + (merge 0971e99 bw/config-lift-variable-name-length-limit later to maint). + + * The "say" function in the test scaffolding incorrectly allowed + "echo" to interpret "\a" as if it were a C-string asking for a + BEL output. + (merge 7bc0911 jc/test-say-color-avoid-echo-escape later to maint). + + * "git mergetool" feeds /dev/null as a common ancestor when dealing + with an add/add conflict, but p4merge backend cannot handle + it. Work it around by passing a temporary empty file. + (merge 3facc60 da/mergetools-p4 later to maint). + + * "git log -F -E --grep='<ere>'" failed to use the given <ere> + pattern as extended regular expression, and instead looked for the + string literally. + (merge 727b6fc jc/grep-pcre-loose-ends~1 later to maint). + + * "git grep -e pattern <tree>" asked the attribute system to read + "<tree>:.gitattributes" file in the working tree, which was + nonsense. + (merge 55c6168 nd/grep-true-path later to maint). + + * A symbolic ref refs/heads/SYM was not correctly removed with "git + branch -d SYM"; the command removed the ref pointed by SYM + instead. + (merge 13baa9f rs/branch-del-symref later to maint). + + * Update "remote tracking branch" in the documentation to + "remote-tracking branch". + (merge a6d3bde mm/maint-doc-remote-tracking later to maint). + + * "git pull --rebase" run while the HEAD is detached tried to find + the upstream branch of the detached HEAD (which by definition + does not exist) and emitted unnecessary error messages. + (merge e980765 ph/pull-rebase-detached later to maint). + + * The refs/replace hierarchy was not mentioned in the + repository-layout docs. + (merge 11fbe18 po/maint-refs-replace-docs later to maint). + + * Various rfc2047 quoting issues around a non-ASCII name on the + From: line in the output from format-patch has been corrected. + (merge 25dc8da js/format-2047 later to maint). + + * Sometimes curl_multi_timeout() function suggested a wrong timeout + value when there is no file descriptors to wait on and the http + transport ended up sleeping for minutes in select(2) system call. + A workaround has been added for this. + (merge 7202b81 sz/maint-curl-multi-timeout later to maint). + + * For a fetch refspec (or the result of applying wildcard on one), + we always want the RHS to map to something inside "refs/" + hierarchy, but the logic to check it was not exactly right. + (merge 5c08c1f jc/maint-fetch-tighten-refname-check later to maint). + + * "git diff -G<pattern>" did not honor textconv filter when looking + for changes. + (merge b1c2f57 jk/maint-diff-grep-textconv later to maint).
diff --git a/cmds-plumbingmanipulators.txt b/cmds-plumbingmanipulators.txt index c2827ac..ef699b4 100644 --- a/cmds-plumbingmanipulators.txt +++ b/cmds-plumbingmanipulators.txt
@@ -35,7 +35,7 @@ Reads tree information into the index. linkgit:git-symbolic-ref[1]:: - Read and modify symbolic refs. + Read, modify and delete symbolic refs. linkgit:git-unpack-objects[1]:: Unpack objects from a packed archive.
diff --git a/git-commit.html b/git-commit.html index 6e0d1af..7811aef 100644 --- a/git-commit.html +++ b/git-commit.html
@@ -917,6 +917,16 @@ </p> </dd> <dt class="hdlist1"> +--no-edit +</dt> +<dd> +<p> + Use the selected commit message without launching an editor. + For example, <tt>git commit --amend --no-edit</tt> amends a commit + without changing its commit message. +</p> +</dd> +<dt class="hdlist1"> --amend </dt> <dd> @@ -930,6 +940,17 @@ the current tip as parents — so the current top commit is discarded. </p> +<div class="paragraph"><p>It is a rough equivalent for:</p></div> +<div class="listingblock"> +<div class="content"> +<pre><tt> $ git reset --soft HEAD^ + $ ... do something else to come up with the right tree ... + $ git commit -c ORIG_HEAD</tt></pre> +</div></div> +<div class="paragraph"><p>but can be used to amend a merge commit.</p></div> +<div class="paragraph"><p>You should understand the implications of rewriting history if you +amend a commit that has already been published. (See the "RECOVERING +FROM UPSTREAM REBASE" section in <a href="git-rebase.html">git-rebase(1)</a>.)</p></div> </dd> <dt class="hdlist1"> --no-post-rewrite @@ -939,21 +960,6 @@ Bypass the post-rewrite hook. </p> </dd> -</dl></div> -<div class="paragraph"><p>+</p></div> -<div class="paragraph"><p>It is a rough equivalent for:</p></div> -<div class="listingblock"> -<div class="content"> -<pre><tt> $ git reset --soft HEAD^ - $ ... do something else to come up with the right tree ... - $ git commit -c ORIG_HEAD</tt></pre> -</div></div> -<div class="paragraph"><p>but can be used to amend a merge commit.</p></div> -<div class="paragraph"><p>+ -You should understand the implications of rewriting history if you -amend a commit that has already been published. (See the "RECOVERING -FROM UPSTREAM REBASE" section in <a href="git-rebase.html">git-rebase(1)</a>.)</p></div> -<div class="dlist"><dl> <dt class="hdlist1"> -i </dt> @@ -1369,7 +1375,7 @@ <div id="footnotes"><hr /></div> <div id="footer"> <div id="footer-text"> -Last updated 2012-11-13 14:31:09 PDT +Last updated 2012-11-15 13:11:54 PDT </div> </div> </body>
diff --git a/git-commit.txt b/git-commit.txt index 0295890..7bdb039 100644 --- a/git-commit.txt +++ b/git-commit.txt
@@ -188,6 +188,11 @@ commit log message unmodified. This option lets you further edit the message taken from these sources. +--no-edit:: + Use the selected commit message without launching an editor. + For example, `git commit --amend --no-edit` amends a commit + without changing its commit message. + --amend:: Used to amend the tip of the current branch. Prepare the tree object you would want to replace the latest commit as usual @@ -197,10 +202,6 @@ current tip -- if it was a merge, it will have the parents of the current tip as parents -- so the current top commit is discarded. - ---no-post-rewrite:: - Bypass the post-rewrite hook. - + -- It is a rough equivalent for: @@ -217,6 +218,9 @@ amend a commit that has already been published. (See the "RECOVERING FROM UPSTREAM REBASE" section in linkgit:git-rebase[1].) +--no-post-rewrite:: + Bypass the post-rewrite hook. + -i:: --include:: Before making a commit out of staged contents so far,
diff --git a/git-cvsimport.html b/git-cvsimport.html index 25b2c91..47fed71 100644 --- a/git-cvsimport.html +++ b/git-cvsimport.html
@@ -798,16 +798,18 @@ <p> CVS by default uses the Unix username when writing its commit logs. Using this option and an author-conv-file - in this format + maps the name recorded in CVS to author name, e-mail and + optional timezone: </p> <div class="listingblock"> <div class="content"> <pre><tt> exon=Andreas Ericsson <ae@op5.se> - spawn=Simon Pawn <spawn@frog-pond.org></tt></pre> + spawn=Simon Pawn <spawn@frog-pond.org> America/Chicago</tt></pre> </div></div> <div class="paragraph"><p><em>git cvsimport</em> will make it appear as those authors had their GIT_AUTHOR_NAME and GIT_AUTHOR_EMAIL set properly -all along.</p></div> +all along. If a timezone is specified, GIT_AUTHOR_DATE will +have the corresponding offset applied.</p></div> <div class="paragraph"><p>For convenience, this data is saved to <tt>$GIT_DIR/cvs-authors</tt> each time the <em>-A</em> option is provided and read from that same file each time <em>git cvsimport</em> is run.</p></div> @@ -928,7 +930,7 @@ <div id="footnotes"><hr /></div> <div id="footer"> <div id="footer-text"> -Last updated 2011-11-15 13:45:02 PDT +Last updated 2012-11-15 13:11:54 PDT </div> </div> </body>
diff --git a/git-cvsimport.txt b/git-cvsimport.txt index 6695ab3..98d9881 100644 --- a/git-cvsimport.txt +++ b/git-cvsimport.txt
@@ -137,17 +137,19 @@ -A <author-conv-file>:: CVS by default uses the Unix username when writing its commit logs. Using this option and an author-conv-file - in this format + maps the name recorded in CVS to author name, e-mail and + optional timezone: + --------- exon=Andreas Ericsson <ae@op5.se> - spawn=Simon Pawn <spawn@frog-pond.org> + spawn=Simon Pawn <spawn@frog-pond.org> America/Chicago --------- + 'git cvsimport' will make it appear as those authors had their GIT_AUTHOR_NAME and GIT_AUTHOR_EMAIL set properly -all along. +all along. If a timezone is specified, GIT_AUTHOR_DATE will +have the corresponding offset applied. + For convenience, this data is saved to `$GIT_DIR/cvs-authors` each time the '-A' option is provided and read from that same
diff --git a/git-format-patch.html b/git-format-patch.html index d1d06f7..60107a5 100644 --- a/git-format-patch.html +++ b/git-format-patch.html
@@ -594,7 +594,7 @@ [--ignore-if-in-upstream] [--subject-prefix=Subject-Prefix] [--to=<email>] [--cc=<email>] - [--cover-letter] [--quiet] + [--cover-letter] [--quiet] [--notes[=<ref>]] [<common diff options>] [ <since> | <revision range> ]</div> <div class="verseblock-attribution"> @@ -1351,6 +1351,22 @@ </p> </dd> <dt class="hdlist1"> +--notes[=<ref>] +</dt> +<dd> +<p> + Append the notes (see <a href="git-notes.html">git-notes(1)</a>) for the commit + after the three-dash line. +</p> +<div class="paragraph"><p>The expected use case of this is to write supporting explanation for +the commit that does not belong to the commit log message proper, +and include it with the patch submission. While one can simply write +these explanations after <tt>format-patch</tt> has run but before sending, +keeping them as git notes allows them to be maintained between versions +of the patch series (but see the discussion of the <tt>notes.rewrite</tt> +configuration options in <a href="git-notes.html">git-notes(1)</a> to use this workflow).</p></div> +</dd> +<dt class="hdlist1"> --[no]-signature=<signature> </dt> <dd> @@ -1771,7 +1787,7 @@ <div id="footnotes"><hr /></div> <div id="footer"> <div id="footer-text"> -Last updated 2012-09-17 16:55:59 PDT +Last updated 2012-11-15 13:11:54 PDT </div> </div> </body>
diff --git a/git-format-patch.txt b/git-format-patch.txt index 6d43f56..259dce4 100644 --- a/git-format-patch.txt +++ b/git-format-patch.txt
@@ -20,7 +20,7 @@ [--ignore-if-in-upstream] [--subject-prefix=Subject-Prefix] [--to=<email>] [--cc=<email>] - [--cover-letter] [--quiet] + [--cover-letter] [--quiet] [--notes[=<ref>]] [<common diff options>] [ <since> | <revision range> ] @@ -191,6 +191,18 @@ containing the shortlog and the overall diffstat. You can fill in a description in the file before sending it out. +--notes[=<ref>]:: + Append the notes (see linkgit:git-notes[1]) for the commit + after the three-dash line. ++ +The expected use case of this is to write supporting explanation for +the commit that does not belong to the commit log message proper, +and include it with the patch submission. While one can simply write +these explanations after `format-patch` has run but before sending, +keeping them as git notes allows them to be maintained between versions +of the patch series (but see the discussion of the `notes.rewrite` +configuration options in linkgit:git-notes[1] to use this workflow). + --[no]-signature=<signature>:: Add a signature to each message produced. Per RFC 3676 the signature is separated from the body by a line with '-- ' on it. If the
diff --git a/git-notes.html b/git-notes.html index 123dd14..4f813cd 100644 --- a/git-notes.html +++ b/git-notes.html
@@ -612,6 +612,9 @@ message stored in the commit object, the notes are indented like the message, after an unindented line saying "Notes (<refname>):" (or "Notes:" for <tt>refs/notes/commits</tt>).</p></div> +<div class="paragraph"><p>Notes can also be added to patches prepared with <tt>git format-patch</tt> by +using the <tt>--notes</tt> option. Such notes are added as a patch commentary +after a three dash separator line.</p></div> <div class="paragraph"><p>To change which notes are shown by <em>git log</em>, see the "notes.displayRef" configuration in <a href="git-log.html">git-log(1)</a>.</p></div> <div class="paragraph"><p>See the "notes.rewrite.<command>" configuration for a way to carry @@ -1126,7 +1129,7 @@ <div id="footnotes"><hr /></div> <div id="footer"> <div id="footer-text"> -Last updated 2012-05-02 15:00:44 PDT +Last updated 2012-11-15 13:11:54 PDT </div> </div> </body>
diff --git a/git-notes.txt b/git-notes.txt index b95aafa..46ef046 100644 --- a/git-notes.txt +++ b/git-notes.txt
@@ -39,6 +39,10 @@ message, after an unindented line saying "Notes (<refname>):" (or "Notes:" for `refs/notes/commits`). +Notes can also be added to patches prepared with `git format-patch` by +using the `--notes` option. Such notes are added as a patch commentary +after a three dash separator line. + To change which notes are shown by 'git log', see the "notes.displayRef" configuration in linkgit:git-log[1].
diff --git a/git-symbolic-ref.html b/git-symbolic-ref.html index 1531d4c..6dd8e62 100644 --- a/git-symbolic-ref.html +++ b/git-symbolic-ref.html
@@ -575,7 +575,7 @@ <h2>NAME</h2> <div class="sectionbody"> <p>git-symbolic-ref - - Read and modify symbolic refs + Read, modify and delete symbolic refs </p> </div> </div> @@ -584,7 +584,8 @@ <div class="sectionbody"> <div class="verseblock"> <div class="verseblock-content"><em>git symbolic-ref</em> [-m <reason>] <name> <ref> -<em>git symbolic-ref</em> [-q] [--short] <name></div> +<em>git symbolic-ref</em> [-q] [--short] <name> +<em>git symbolic-ref</em> --delete [-q] <name></div> <div class="verseblock-attribution"> </div></div> </div> @@ -596,6 +597,8 @@ argument to see which branch your working tree is on.</p></div> <div class="paragraph"><p>Given two arguments, creates or updates a symbolic ref <name> to point at the given branch <ref>.</p></div> +<div class="paragraph"><p>Given <tt>--delete</tt> and an additional argument, deletes the given +symbolic ref.</p></div> <div class="paragraph"><p>A symbolic ref is a regular file that stores a string that begins with <tt>ref: refs/</tt>. For example, your <tt>.git/HEAD</tt> is a regular file whose contents is <tt>ref: refs/heads/master</tt>.</p></div> @@ -604,6 +607,17 @@ <div class="sectionbody"> <div class="dlist"><dl> <dt class="hdlist1"> +-d +</dt> +<dt class="hdlist1"> +--delete +</dt> +<dd> +<p> + Delete the symbolic ref <name>. +</p> +</dd> +<dt class="hdlist1"> -q </dt> <dt class="hdlist1"> @@ -657,7 +671,7 @@ <div id="footnotes"><hr /></div> <div id="footer"> <div id="footer-text"> -Last updated 2012-03-04 23:48:43 PDT +Last updated 2012-11-15 13:11:54 PDT </div> </div> </body>
diff --git a/git-symbolic-ref.txt b/git-symbolic-ref.txt index 981d3a8..ef68ad2 100644 --- a/git-symbolic-ref.txt +++ b/git-symbolic-ref.txt
@@ -3,13 +3,14 @@ NAME ---- -git-symbolic-ref - Read and modify symbolic refs +git-symbolic-ref - Read, modify and delete symbolic refs SYNOPSIS -------- [verse] 'git symbolic-ref' [-m <reason>] <name> <ref> 'git symbolic-ref' [-q] [--short] <name> +'git symbolic-ref' --delete [-q] <name> DESCRIPTION ----------- @@ -21,6 +22,9 @@ Given two arguments, creates or updates a symbolic ref <name> to point at the given branch <ref>. +Given `--delete` and an additional argument, deletes the given +symbolic ref. + A symbolic ref is a regular file that stores a string that begins with `ref: refs/`. For example, your `.git/HEAD` is a regular file whose contents is `ref: refs/heads/master`. @@ -28,6 +32,10 @@ OPTIONS ------- +-d:: +--delete:: + Delete the symbolic ref <name>. + -q:: --quiet:: Do not issue an error message if the <name> is not a
diff --git a/git.html b/git.html index 82c2715..cdf5365 100644 --- a/git.html +++ b/git.html
@@ -1520,7 +1520,7 @@ </dt> <dd> <p> - Read and modify symbolic refs. + Read, modify and delete symbolic refs. </p> </dd> <dt class="hdlist1">
diff --git a/technical/api-strbuf.html b/technical/api-strbuf.html index cbe2515..5cf02e3 100644 --- a/technical/api-strbuf.html +++ b/technical/api-strbuf.html
@@ -1024,6 +1024,36 @@ </p> </dd> <dt class="hdlist1"> +<tt>strbuf_split_buf</tt> +</dt> +<dt class="hdlist1"> +<tt>strbuf_split_str</tt> +</dt> +<dt class="hdlist1"> +<tt>strbuf_split_max</tt> +</dt> +<dt class="hdlist1"> +<tt>strbuf_split</tt> +</dt> +<dd> +<p> + Split a string or strbuf into a list of strbufs at a specified + terminator character. The returned substrings include the + terminator characters. Some of these functions take a <tt>max</tt> + parameter, which, if positive, limits the output to that + number of substrings. +</p> +</dd> +<dt class="hdlist1"> +<tt>strbuf_list_free</tt> +</dt> +<dd> +<p> + Free a list of strbufs (for example, the return values of the + <tt>strbuf_split()</tt> functions). +</p> +</dd> +<dt class="hdlist1"> <tt>launch_editor</tt> </dt> <dd> @@ -1041,7 +1071,7 @@ <div id="footnotes"><hr /></div> <div id="footer"> <div id="footer-text"> -Last updated 2012-02-26 23:49:05 PDT +Last updated 2012-11-15 13:11:54 PDT </div> </div> </body>
diff --git a/technical/api-strbuf.txt b/technical/api-strbuf.txt index 95a8bf3..84686b5 100644 --- a/technical/api-strbuf.txt +++ b/technical/api-strbuf.txt
@@ -279,6 +279,22 @@ Strip whitespace from a buffer. The second parameter controls if comments are considered contents to be removed or not. +`strbuf_split_buf`:: +`strbuf_split_str`:: +`strbuf_split_max`:: +`strbuf_split`:: + + Split a string or strbuf into a list of strbufs at a specified + terminator character. The returned substrings include the + terminator characters. Some of these functions take a `max` + parameter, which, if positive, limits the output to that + number of substrings. + +`strbuf_list_free`:: + + Free a list of strbufs (for example, the return values of the + `strbuf_split()` functions). + `launch_editor`:: Launch the user preferred editor to edit a file and fill the buffer
diff --git a/technical/api-string-list.html b/technical/api-string-list.html index 67b1986..c0db761 100644 --- a/technical/api-string-list.html +++ b/technical/api-string-list.html
@@ -613,7 +613,8 @@ <li> <p> Can remove items not matching a criterion from a sorted or unsorted - list using <tt>filter_string_list</tt>. + list using <tt>filter_string_list</tt>, or remove empty strings using + <tt>string_list_remove_empty_items</tt>. </p> </li> <li> @@ -670,6 +671,16 @@ </p> </dd> <dt class="hdlist1"> +<tt>string_list_remove_empty_items</tt> +</dt> +<dd> +<p> + Remove any empty strings from the list. If free_util is true, + call free() on the util members of any items that have to be + deleted. Preserve the order of the items that are retained. +</p> +</dd> +<dt class="hdlist1"> <tt>string_list_longest_prefix</tt> </dt> <dd> @@ -893,7 +904,7 @@ <div id="footnotes"><hr /></div> <div id="footer"> <div id="footer-text"> -Last updated 2012-09-24 14:27:45 PDT +Last updated 2012-11-15 13:11:54 PDT </div> </div> </body>
diff --git a/technical/api-string-list.txt b/technical/api-string-list.txt index 94d7a2b..7386bca 100644 --- a/technical/api-string-list.txt +++ b/technical/api-string-list.txt
@@ -38,7 +38,8 @@ `unsorted_string_list_delete_item`. . Can remove items not matching a criterion from a sorted or unsorted - list using `filter_string_list`. + list using `filter_string_list`, or remove empty strings using + `string_list_remove_empty_items`. . Finally it should free the list using `string_list_clear`. @@ -75,6 +76,12 @@ to be deleted. Preserve the order of the items that are retained. +`string_list_remove_empty_items`:: + + Remove any empty strings from the list. If free_util is true, + call free() on the util members of any items that have to be + deleted. Preserve the order of the items that are retained. + `string_list_longest_prefix`:: Return the longest string within a string_list that is a
diff --git a/user-manual.html b/user-manual.html index 56d35fa..4bd6df5 100644 --- a/user-manual.html +++ b/user-manual.html
@@ -1,5 +1,5 @@ <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01//EN" "http://www.w3.org/TR/html4/strict.dtd"> -<html><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8"><title>Git User’s Manual (for version 1.5.3 or newer)</title><link rel="stylesheet" href="docbook-xsl.css" type="text/css"><meta name="generator" content="DocBook XSL Stylesheets V1.75.2"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div lang="en" class="book" title="Git User’s Manual (for version 1.5.3 or newer)"><div class="titlepage"><div><div><h1 class="title"><a name="idp167312"></a>Git User’s Manual (for version 1.5.3 or newer)</h1></div></div><hr></div><div class="toc"><p><b>Table of Contents</b></p><dl><dt><span class="preface"><a href="#idp168560"></a></span></dt><dt><span class="chapter"><a href="#repositories-and-branches">1. Repositories and Branches</a></span></dt><dd><dl><dt><span class="section"><a href="#how-to-get-a-git-repository">How to get a git repository</a></span></dt><dt><span class="section"><a href="#how-to-check-out">How to check out a different version of a project</a></span></dt><dt><span class="section"><a href="#understanding-commits">Understanding History: Commits</a></span></dt><dd><dl><dt><span class="section"><a href="#understanding-reachability">Understanding history: commits, parents, and reachability</a></span></dt><dt><span class="section"><a href="#history-diagrams">Understanding history: History diagrams</a></span></dt><dt><span class="section"><a href="#what-is-a-branch">Understanding history: What is a branch?</a></span></dt></dl></dd><dt><span class="section"><a href="#manipulating-branches">Manipulating branches</a></span></dt><dt><span class="section"><a href="#detached-head">Examining an old version without creating a new branch</a></span></dt><dt><span class="section"><a href="#examining-remote-branches">Examining branches from a remote repository</a></span></dt><dt><span class="section"><a href="#how-git-stores-references">Naming branches, tags, and other references</a></span></dt><dt><span class="section"><a href="#Updating-a-repository-With-git-fetch">Updating a repository with git fetch</a></span></dt><dt><span class="section"><a href="#fetching-branches">Fetching branches from other repositories</a></span></dt></dl></dd><dt><span class="chapter"><a href="#exploring-git-history">2. Exploring git history</a></span></dt><dd><dl><dt><span class="section"><a href="#using-bisect">How to use bisect to find a regression</a></span></dt><dt><span class="section"><a href="#naming-commits">Naming commits</a></span></dt><dt><span class="section"><a href="#creating-tags">Creating tags</a></span></dt><dt><span class="section"><a href="#browsing-revisions">Browsing revisions</a></span></dt><dt><span class="section"><a href="#generating-diffs">Generating diffs</a></span></dt><dt><span class="section"><a href="#viewing-old-file-versions">Viewing old file versions</a></span></dt><dt><span class="section"><a href="#history-examples">Examples</a></span></dt><dd><dl><dt><span class="section"><a href="#counting-commits-on-a-branch">Counting the number of commits on a branch</a></span></dt><dt><span class="section"><a href="#checking-for-equal-branches">Check whether two branches point at the same history</a></span></dt><dt><span class="section"><a href="#finding-tagged-descendants">Find first tagged version including a given fix</a></span></dt><dt><span class="section"><a href="#showing-commits-unique-to-a-branch">Showing commits unique to a given branch</a></span></dt><dt><span class="section"><a href="#making-a-release">Creating a changelog and tarball for a software release</a></span></dt><dt><span class="section"><a href="#Finding-commits-With-given-Content">Finding commits referencing a file with given content</a></span></dt></dl></dd></dl></dd><dt><span class="chapter"><a href="#Developing-With-git">3. Developing with git</a></span></dt><dd><dl><dt><span class="section"><a href="#telling-git-your-name">Telling git your name</a></span></dt><dt><span class="section"><a href="#creating-a-new-repository">Creating a new repository</a></span></dt><dt><span class="section"><a href="#how-to-make-a-commit">How to make a commit</a></span></dt><dt><span class="section"><a href="#creating-good-commit-messages">Creating good commit messages</a></span></dt><dt><span class="section"><a href="#ignoring-files">Ignoring files</a></span></dt><dt><span class="section"><a href="#how-to-merge">How to merge</a></span></dt><dt><span class="section"><a href="#resolving-a-merge">Resolving a merge</a></span></dt><dd><dl><dt><span class="section"><a href="#conflict-resolution">Getting conflict-resolution help during a merge</a></span></dt></dl></dd><dt><span class="section"><a href="#undoing-a-merge">Undoing a merge</a></span></dt><dt><span class="section"><a href="#fast-forwards">Fast-forward merges</a></span></dt><dt><span class="section"><a href="#fixing-mistakes">Fixing mistakes</a></span></dt><dd><dl><dt><span class="section"><a href="#reverting-a-commit">Fixing a mistake with a new commit</a></span></dt><dt><span class="section"><a href="#fixing-a-mistake-by-rewriting-history">Fixing a mistake by rewriting history</a></span></dt><dt><span class="section"><a href="#checkout-of-path">Checking out an old version of a file</a></span></dt><dt><span class="section"><a href="#interrupted-work">Temporarily setting aside work in progress</a></span></dt></dl></dd><dt><span class="section"><a href="#ensuring-good-performance">Ensuring good performance</a></span></dt><dt><span class="section"><a href="#ensuring-reliability">Ensuring reliability</a></span></dt><dd><dl><dt><span class="section"><a href="#checking-for-corruption">Checking the repository for corruption</a></span></dt><dt><span class="section"><a href="#recovering-lost-changes">Recovering lost changes</a></span></dt></dl></dd></dl></dd><dt><span class="chapter"><a href="#sharing-development">4. Sharing development with others</a></span></dt><dd><dl><dt><span class="section"><a href="#getting-updates-With-git-pull">Getting updates with git pull</a></span></dt><dt><span class="section"><a href="#submitting-patches">Submitting patches to a project</a></span></dt><dt><span class="section"><a href="#importing-patches">Importing patches to a project</a></span></dt><dt><span class="section"><a href="#public-repositories">Public git repositories</a></span></dt><dd><dl><dt><span class="section"><a href="#setting-up-a-public-repository">Setting up a public repository</a></span></dt><dt><span class="section"><a href="#exporting-via-git">Exporting a git repository via the git protocol</a></span></dt><dt><span class="section"><a href="#exporting-via-http">Exporting a git repository via http</a></span></dt><dt><span class="section"><a href="#pushing-changes-to-a-public-repository">Pushing changes to a public repository</a></span></dt><dt><span class="section"><a href="#forcing-push">What to do when a push fails</a></span></dt><dt><span class="section"><a href="#setting-up-a-shared-repository">Setting up a shared repository</a></span></dt><dt><span class="section"><a href="#setting-up-gitweb">Allowing web browsing of a repository</a></span></dt></dl></dd><dt><span class="section"><a href="#sharing-development-examples">Examples</a></span></dt><dd><dl><dt><span class="section"><a href="#maintaining-topic-branches">Maintaining topic branches for a Linux subsystem maintainer</a></span></dt></dl></dd></dl></dd><dt><span class="chapter"><a href="#cleaning-up-history">5. Rewriting history and maintaining patch series</a></span></dt><dd><dl><dt><span class="section"><a href="#patch-series">Creating the perfect patch series</a></span></dt><dt><span class="section"><a href="#using-git-rebase">Keeping a patch series up to date using git rebase</a></span></dt><dt><span class="section"><a href="#rewriting-one-commit">Rewriting a single commit</a></span></dt><dt><span class="section"><a href="#reordering-patch-series">Reordering or selecting from a patch series</a></span></dt><dt><span class="section"><a href="#patch-series-tools">Other tools</a></span></dt><dt><span class="section"><a href="#problems-With-rewriting-history">Problems with rewriting history</a></span></dt><dt><span class="section"><a href="#bisect-merges">Why bisecting merge commits can be harder than bisecting linear history</a></span></dt></dl></dd><dt><span class="chapter"><a href="#advanced-branch-management">6. Advanced branch management</a></span></dt><dd><dl><dt><span class="section"><a href="#fetching-individual-branches">Fetching individual branches</a></span></dt><dt><span class="section"><a href="#fetch-fast-forwards">git fetch and fast-forwards</a></span></dt><dt><span class="section"><a href="#forcing-fetch">Forcing git fetch to do non-fast-forward updates</a></span></dt><dt><span class="section"><a href="#remote-branch-configuration">Configuring remote-tracking branches</a></span></dt></dl></dd><dt><span class="chapter"><a href="#git-concepts">7. Git concepts</a></span></dt><dd><dl><dt><span class="section"><a href="#the-object-database">The Object Database</a></span></dt><dd><dl><dt><span class="section"><a href="#commit-object">Commit Object</a></span></dt><dt><span class="section"><a href="#tree-object">Tree Object</a></span></dt><dt><span class="section"><a href="#blob-object">Blob Object</a></span></dt><dt><span class="section"><a href="#trust">Trust</a></span></dt><dt><span class="section"><a href="#tag-object">Tag Object</a></span></dt><dt><span class="section"><a href="#pack-files">How git stores objects efficiently: pack files</a></span></dt><dt><span class="section"><a href="#dangling-objects">Dangling objects</a></span></dt><dt><span class="section"><a href="#recovering-from-repository-corruption">Recovering from repository corruption</a></span></dt></dl></dd><dt><span class="section"><a href="#the-index">The index</a></span></dt></dl></dd><dt><span class="chapter"><a href="#submodules">8. Submodules</a></span></dt><dd><dl><dt><span class="section"><a href="#_pitfalls_with_submodules">Pitfalls with submodules</a></span></dt></dl></dd><dt><span class="chapter"><a href="#low-level-operations">9. Low-level git operations</a></span></dt><dd><dl><dt><span class="section"><a href="#object-manipulation">Object access and manipulation</a></span></dt><dt><span class="section"><a href="#the-workflow">The Workflow</a></span></dt><dd><dl><dt><span class="section"><a href="#working-directory-to-index">working directory → index</a></span></dt><dt><span class="section"><a href="#index-to-object-database">index → object database</a></span></dt><dt><span class="section"><a href="#object-database-to-index">object database → index</a></span></dt><dt><span class="section"><a href="#index-to-working-directory">index → working directory</a></span></dt><dt><span class="section"><a href="#tying-it-all-together">Tying it all together</a></span></dt></dl></dd><dt><span class="section"><a href="#examining-the-data">Examining the data</a></span></dt><dt><span class="section"><a href="#merging-multiple-trees">Merging multiple trees</a></span></dt><dt><span class="section"><a href="#merging-multiple-trees-2">Merging multiple trees, continued</a></span></dt></dl></dd><dt><span class="chapter"><a href="#hacking-git">10. Hacking git</a></span></dt><dd><dl><dt><span class="section"><a href="#object-details">Object storage format</a></span></dt><dt><span class="section"><a href="#birdview-on-the-source-code">A birds-eye view of Git’s source code</a></span></dt></dl></dd><dt><span class="chapter"><a href="#glossary">11. Git Glossary</a></span></dt><dt><span class="appendix"><a href="#git-quick-start">A. Git Quick Reference</a></span></dt><dd><dl><dt><span class="section"><a href="#quick-creating-a-new-repository">Creating a new repository</a></span></dt><dt><span class="section"><a href="#managing-branches">Managing branches</a></span></dt><dt><span class="section"><a href="#exploring-history">Exploring history</a></span></dt><dt><span class="section"><a href="#making-changes">Making changes</a></span></dt><dt><span class="section"><a href="#merging">Merging</a></span></dt><dt><span class="section"><a href="#sharing-your-changes">Sharing your changes</a></span></dt><dt><span class="section"><a href="#repository-maintenance">Repository maintenance</a></span></dt></dl></dd><dt><span class="appendix"><a href="#todo">B. Notes and todo list for this manual</a></span></dt></dl></div><div class="preface"><div class="titlepage"><div><div><h2 class="title"><a name="idp168560"></a></h2></div></div></div><p>Git is a fast distributed revision control system.</p><p>This manual is designed to be readable by someone with basic UNIX +<html><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8"><title>Git User’s Manual (for version 1.5.3 or newer)</title><link rel="stylesheet" href="docbook-xsl.css" type="text/css"><meta name="generator" content="DocBook XSL Stylesheets V1.75.2"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div lang="en" class="book" title="Git User’s Manual (for version 1.5.3 or newer)"><div class="titlepage"><div><div><h1 class="title"><a name="idp146304"></a>Git User’s Manual (for version 1.5.3 or newer)</h1></div></div><hr></div><div class="toc"><p><b>Table of Contents</b></p><dl><dt><span class="preface"><a href="#idp147696"></a></span></dt><dt><span class="chapter"><a href="#repositories-and-branches">1. Repositories and Branches</a></span></dt><dd><dl><dt><span class="section"><a href="#how-to-get-a-git-repository">How to get a git repository</a></span></dt><dt><span class="section"><a href="#how-to-check-out">How to check out a different version of a project</a></span></dt><dt><span class="section"><a href="#understanding-commits">Understanding History: Commits</a></span></dt><dd><dl><dt><span class="section"><a href="#understanding-reachability">Understanding history: commits, parents, and reachability</a></span></dt><dt><span class="section"><a href="#history-diagrams">Understanding history: History diagrams</a></span></dt><dt><span class="section"><a href="#what-is-a-branch">Understanding history: What is a branch?</a></span></dt></dl></dd><dt><span class="section"><a href="#manipulating-branches">Manipulating branches</a></span></dt><dt><span class="section"><a href="#detached-head">Examining an old version without creating a new branch</a></span></dt><dt><span class="section"><a href="#examining-remote-branches">Examining branches from a remote repository</a></span></dt><dt><span class="section"><a href="#how-git-stores-references">Naming branches, tags, and other references</a></span></dt><dt><span class="section"><a href="#Updating-a-repository-With-git-fetch">Updating a repository with git fetch</a></span></dt><dt><span class="section"><a href="#fetching-branches">Fetching branches from other repositories</a></span></dt></dl></dd><dt><span class="chapter"><a href="#exploring-git-history">2. Exploring git history</a></span></dt><dd><dl><dt><span class="section"><a href="#using-bisect">How to use bisect to find a regression</a></span></dt><dt><span class="section"><a href="#naming-commits">Naming commits</a></span></dt><dt><span class="section"><a href="#creating-tags">Creating tags</a></span></dt><dt><span class="section"><a href="#browsing-revisions">Browsing revisions</a></span></dt><dt><span class="section"><a href="#generating-diffs">Generating diffs</a></span></dt><dt><span class="section"><a href="#viewing-old-file-versions">Viewing old file versions</a></span></dt><dt><span class="section"><a href="#history-examples">Examples</a></span></dt><dd><dl><dt><span class="section"><a href="#counting-commits-on-a-branch">Counting the number of commits on a branch</a></span></dt><dt><span class="section"><a href="#checking-for-equal-branches">Check whether two branches point at the same history</a></span></dt><dt><span class="section"><a href="#finding-tagged-descendants">Find first tagged version including a given fix</a></span></dt><dt><span class="section"><a href="#showing-commits-unique-to-a-branch">Showing commits unique to a given branch</a></span></dt><dt><span class="section"><a href="#making-a-release">Creating a changelog and tarball for a software release</a></span></dt><dt><span class="section"><a href="#Finding-commits-With-given-Content">Finding commits referencing a file with given content</a></span></dt></dl></dd></dl></dd><dt><span class="chapter"><a href="#Developing-With-git">3. Developing with git</a></span></dt><dd><dl><dt><span class="section"><a href="#telling-git-your-name">Telling git your name</a></span></dt><dt><span class="section"><a href="#creating-a-new-repository">Creating a new repository</a></span></dt><dt><span class="section"><a href="#how-to-make-a-commit">How to make a commit</a></span></dt><dt><span class="section"><a href="#creating-good-commit-messages">Creating good commit messages</a></span></dt><dt><span class="section"><a href="#ignoring-files">Ignoring files</a></span></dt><dt><span class="section"><a href="#how-to-merge">How to merge</a></span></dt><dt><span class="section"><a href="#resolving-a-merge">Resolving a merge</a></span></dt><dd><dl><dt><span class="section"><a href="#conflict-resolution">Getting conflict-resolution help during a merge</a></span></dt></dl></dd><dt><span class="section"><a href="#undoing-a-merge">Undoing a merge</a></span></dt><dt><span class="section"><a href="#fast-forwards">Fast-forward merges</a></span></dt><dt><span class="section"><a href="#fixing-mistakes">Fixing mistakes</a></span></dt><dd><dl><dt><span class="section"><a href="#reverting-a-commit">Fixing a mistake with a new commit</a></span></dt><dt><span class="section"><a href="#fixing-a-mistake-by-rewriting-history">Fixing a mistake by rewriting history</a></span></dt><dt><span class="section"><a href="#checkout-of-path">Checking out an old version of a file</a></span></dt><dt><span class="section"><a href="#interrupted-work">Temporarily setting aside work in progress</a></span></dt></dl></dd><dt><span class="section"><a href="#ensuring-good-performance">Ensuring good performance</a></span></dt><dt><span class="section"><a href="#ensuring-reliability">Ensuring reliability</a></span></dt><dd><dl><dt><span class="section"><a href="#checking-for-corruption">Checking the repository for corruption</a></span></dt><dt><span class="section"><a href="#recovering-lost-changes">Recovering lost changes</a></span></dt></dl></dd></dl></dd><dt><span class="chapter"><a href="#sharing-development">4. Sharing development with others</a></span></dt><dd><dl><dt><span class="section"><a href="#getting-updates-With-git-pull">Getting updates with git pull</a></span></dt><dt><span class="section"><a href="#submitting-patches">Submitting patches to a project</a></span></dt><dt><span class="section"><a href="#importing-patches">Importing patches to a project</a></span></dt><dt><span class="section"><a href="#public-repositories">Public git repositories</a></span></dt><dd><dl><dt><span class="section"><a href="#setting-up-a-public-repository">Setting up a public repository</a></span></dt><dt><span class="section"><a href="#exporting-via-git">Exporting a git repository via the git protocol</a></span></dt><dt><span class="section"><a href="#exporting-via-http">Exporting a git repository via http</a></span></dt><dt><span class="section"><a href="#pushing-changes-to-a-public-repository">Pushing changes to a public repository</a></span></dt><dt><span class="section"><a href="#forcing-push">What to do when a push fails</a></span></dt><dt><span class="section"><a href="#setting-up-a-shared-repository">Setting up a shared repository</a></span></dt><dt><span class="section"><a href="#setting-up-gitweb">Allowing web browsing of a repository</a></span></dt></dl></dd><dt><span class="section"><a href="#sharing-development-examples">Examples</a></span></dt><dd><dl><dt><span class="section"><a href="#maintaining-topic-branches">Maintaining topic branches for a Linux subsystem maintainer</a></span></dt></dl></dd></dl></dd><dt><span class="chapter"><a href="#cleaning-up-history">5. Rewriting history and maintaining patch series</a></span></dt><dd><dl><dt><span class="section"><a href="#patch-series">Creating the perfect patch series</a></span></dt><dt><span class="section"><a href="#using-git-rebase">Keeping a patch series up to date using git rebase</a></span></dt><dt><span class="section"><a href="#rewriting-one-commit">Rewriting a single commit</a></span></dt><dt><span class="section"><a href="#reordering-patch-series">Reordering or selecting from a patch series</a></span></dt><dt><span class="section"><a href="#patch-series-tools">Other tools</a></span></dt><dt><span class="section"><a href="#problems-With-rewriting-history">Problems with rewriting history</a></span></dt><dt><span class="section"><a href="#bisect-merges">Why bisecting merge commits can be harder than bisecting linear history</a></span></dt></dl></dd><dt><span class="chapter"><a href="#advanced-branch-management">6. Advanced branch management</a></span></dt><dd><dl><dt><span class="section"><a href="#fetching-individual-branches">Fetching individual branches</a></span></dt><dt><span class="section"><a href="#fetch-fast-forwards">git fetch and fast-forwards</a></span></dt><dt><span class="section"><a href="#forcing-fetch">Forcing git fetch to do non-fast-forward updates</a></span></dt><dt><span class="section"><a href="#remote-branch-configuration">Configuring remote-tracking branches</a></span></dt></dl></dd><dt><span class="chapter"><a href="#git-concepts">7. Git concepts</a></span></dt><dd><dl><dt><span class="section"><a href="#the-object-database">The Object Database</a></span></dt><dd><dl><dt><span class="section"><a href="#commit-object">Commit Object</a></span></dt><dt><span class="section"><a href="#tree-object">Tree Object</a></span></dt><dt><span class="section"><a href="#blob-object">Blob Object</a></span></dt><dt><span class="section"><a href="#trust">Trust</a></span></dt><dt><span class="section"><a href="#tag-object">Tag Object</a></span></dt><dt><span class="section"><a href="#pack-files">How git stores objects efficiently: pack files</a></span></dt><dt><span class="section"><a href="#dangling-objects">Dangling objects</a></span></dt><dt><span class="section"><a href="#recovering-from-repository-corruption">Recovering from repository corruption</a></span></dt></dl></dd><dt><span class="section"><a href="#the-index">The index</a></span></dt></dl></dd><dt><span class="chapter"><a href="#submodules">8. Submodules</a></span></dt><dd><dl><dt><span class="section"><a href="#_pitfalls_with_submodules">Pitfalls with submodules</a></span></dt></dl></dd><dt><span class="chapter"><a href="#low-level-operations">9. Low-level git operations</a></span></dt><dd><dl><dt><span class="section"><a href="#object-manipulation">Object access and manipulation</a></span></dt><dt><span class="section"><a href="#the-workflow">The Workflow</a></span></dt><dd><dl><dt><span class="section"><a href="#working-directory-to-index">working directory → index</a></span></dt><dt><span class="section"><a href="#index-to-object-database">index → object database</a></span></dt><dt><span class="section"><a href="#object-database-to-index">object database → index</a></span></dt><dt><span class="section"><a href="#index-to-working-directory">index → working directory</a></span></dt><dt><span class="section"><a href="#tying-it-all-together">Tying it all together</a></span></dt></dl></dd><dt><span class="section"><a href="#examining-the-data">Examining the data</a></span></dt><dt><span class="section"><a href="#merging-multiple-trees">Merging multiple trees</a></span></dt><dt><span class="section"><a href="#merging-multiple-trees-2">Merging multiple trees, continued</a></span></dt></dl></dd><dt><span class="chapter"><a href="#hacking-git">10. Hacking git</a></span></dt><dd><dl><dt><span class="section"><a href="#object-details">Object storage format</a></span></dt><dt><span class="section"><a href="#birdview-on-the-source-code">A birds-eye view of Git’s source code</a></span></dt></dl></dd><dt><span class="chapter"><a href="#glossary">11. Git Glossary</a></span></dt><dt><span class="appendix"><a href="#git-quick-start">A. Git Quick Reference</a></span></dt><dd><dl><dt><span class="section"><a href="#quick-creating-a-new-repository">Creating a new repository</a></span></dt><dt><span class="section"><a href="#managing-branches">Managing branches</a></span></dt><dt><span class="section"><a href="#exploring-history">Exploring history</a></span></dt><dt><span class="section"><a href="#making-changes">Making changes</a></span></dt><dt><span class="section"><a href="#merging">Merging</a></span></dt><dt><span class="section"><a href="#sharing-your-changes">Sharing your changes</a></span></dt><dt><span class="section"><a href="#repository-maintenance">Repository maintenance</a></span></dt></dl></dd><dt><span class="appendix"><a href="#todo">B. Notes and todo list for this manual</a></span></dt></dl></div><div class="preface"><div class="titlepage"><div><div><h2 class="title"><a name="idp147696"></a></h2></div></div></div><p>Git is a fast distributed revision control system.</p><p>This manual is designed to be readable by someone with basic UNIX command-line skills, but no previous knowledge of git.</p><p><a class="xref" href="#repositories-and-branches" title="Chapter 1. Repositories and Branches">Chapter 1, <i>Repositories and Branches</i></a> and <a class="xref" href="#exploring-git-history" title="Chapter 2. Exploring git history">Chapter 2, <i>Exploring git history</i></a> explain how to fetch and study a project using git—read these chapters to learn how to build and test a particular version of a software project, search for @@ -704,7 +704,12 @@ the commands</p><pre class="literallayout">$ git pull . branch $ git merge branch</pre><p>are roughly equivalent. The former is actually very commonly used.</p></div><div class="section" title="Submitting patches to a project"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="submitting-patches"></a>Submitting patches to a project</h2></div></div></div><p>If you just have a few changes, the simplest way to submit them may just be to send them as patches in email:</p><p>First, use <a class="ulink" href="git-format-patch.html" target="_top">git-format-patch(1)</a>; for example:</p><pre class="literallayout">$ git format-patch origin</pre><p>will produce a numbered series of files in the current directory, one -for each patch in the current branch but not in origin/HEAD.</p><p>You can then import these into your mail client and send them by +for each patch in the current branch but not in origin/HEAD.</p><p><code class="literal">git format-patch</code> can include an initial "cover letter". You can insert +commentary on individual patches after the three dash line which +<code class="literal">format-patch</code> places after the commit message but before the patch +itself. If you use <code class="literal">git notes</code> to track your cover letter material, +<code class="literal">git format-patch --notes</code> will include the commit’s notes in a similar +manner.</p><p>You can then import these into your mail client and send them by hand. However, if you have a lot to send at once, you may prefer to use the <a class="ulink" href="git-send-email.html" target="_top">git-send-email(1)</a> script to automate the process. Consult the mailing list for your project first to determine how they
diff --git a/user-manual.txt b/user-manual.txt index 85651b5..1b377dc 100644 --- a/user-manual.txt +++ b/user-manual.txt
@@ -1787,6 +1787,13 @@ will produce a numbered series of files in the current directory, one for each patch in the current branch but not in origin/HEAD. +`git format-patch` can include an initial "cover letter". You can insert +commentary on individual patches after the three dash line which +`format-patch` places after the commit message but before the patch +itself. If you use `git notes` to track your cover letter material, +`git format-patch --notes` will include the commit's notes in a similar +manner. + You can then import these into your mail client and send them by hand. However, if you have a lot to send at once, you may prefer to use the linkgit:git-send-email[1] script to automate the process.
